/*
 * Copyright 2008 Max Kugland
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.splink.library.distributor {
	import org.splink.library.IFinalizable;

	/**
	 * Basic Interface for <code>IDistributor</code> implementations. An <code>IDistributor</code> 
	 * can register Listeners and distribute <code>IDevent</code>s to them. A Listener consists of type and function.
	 * The type is needed to look up all listeners registred for a particular <code>IDevent</code>. If the 
	 * <code>IDevent</code> is distributed the functions of all registred listeners get called and
	 * provided with the event.
	 * 
	 * The advantage over flashs native event system is that <code>IDistributor</code> is much more lightweight 
	 * and that it is not neccessary to unregister any listeners because in most cases its quicker to 
	 * just finalize <code>IDistributor</code>. In contrast you need either to register a weak reference
	 * with the flash EventDispatcher or remove the event via removeEventListener in order to let the 
	 * garbage collector to do its job.
	 * 
	 * @author Max Kugland
	 */
	public interface IDistributor extends IFinalizable {
		/**
		 * Any object can register with an <code>IDistributor</code> to receive <code>IDevent</code>s.
		 * 
		 * @param type the <code>IDevent</code>s type to register for
		 * @param fnc the function which is invoked by <code>IDistributor</code>
		 * if the event occurs
		 * @param params an optional params object, which might be useful if you wish to pass local
		 * variables to the event consumers
		 * @param priority the optional priority controls the order in which the events are distributed.
		 * The listener with the highest priority gets the event first. Then the listener with the next
		 * highest priority gets the event second and so on. If several events have the same priority 
		 * (which is the default case) they get distributed in the order in which they were registered
		 */
		function register(type : Dtype, fnc : Function, params : Object = null, priority : uint = uint.MIN_VALUE) : IDistributor;

		/**
		 * Unregister removes a previously registred listener.
		 * 
		 * @param type the <code>IDevent</code>s type the listener has been registered with
		 * @param fnc the function which would have been called by <code>IDistributor</code>
		 */
		function unregister(type : Dtype, fnc : Function) : IDistributor;

		/**
		 * Distributes an <code>IDevent</code> to all previously registred listeners for that 
		 * <code>IDevent</code>.
		 * Note, that the <code>IDevent</code> is identified by its type, so be careful with choosing
		 * the type(s) of your <code>IDevent</code> implementing classes.
		 * 
		 * @param event the <code>IDevent</code> to be distributed to registered listeners
		 */
		function distribute(event : IDevent) : void;
	}
}
